COMMENT ⊗   VALID 00028 PAGES
C REC  PAGE   DESCRIPTION
C00001 00001
C00003 00002	Documentation needed!
C00004 00003	The simulator.
C00005 00004	Invoking the simulator.
C00006 00005	Exiting the simulator.
C00007 00006	Demonstrations for beginners.
C00008 00007	More Demonstrations.
C00010 00008	Commands and numeric arguments.
C00012 00009	Getting ALT files from AL.
C00013 00010	Miscellaneous commands.
C00014 00011	Objects in the world.
C00015 00012	Visibility of objects.
C00017 00013	Display modes:  stereo, mono.
C00018 00014	Camera parameters.
C00021 00015	Cameras:  naming, changing, saving, and loading.
C00023 00016	P1 Mode:  the PUMA-500 closer to the door.
C00026 00017	P2 Mode:  the PUMA-500 further from the door.
C00027 00018	ALT files.
C00028 00019	Stepping thru an ALT file.
C00031 00020	Driving the joints of BARM.
C00034 00021	Collision.
C00035 00022	Hardcopy output.
C00038 00023	Some other things to note.
C00040 00024	Digest of top-level keystroke commands.
C00041 00025	Digest of extended commands.
C00042 00026	How to create an ACRSIM.
C00043 00027	Files used by SIMULATOR.
C00044 00028	Archived announcements.
C00052 ENDMK
C⊗;
Documentation needed!

Hand.
The simulator.
 
By:
	07-Jan-80 BIS
	20-Jan-80 BIS
	31-Jan-80 BIS
	21-Mar-80 BIS
	13-Jul-80 BIS
	20-Jul-80 BIS
	11-Aug-80 BIS
 
Notification list:
 
	The distribution list for simulator updates and announcements
	is SIMULA.DIS[DIS,BIS].  Feel free to add or delete your name
	from this file.
 
Bugs:
 
	Send comments, complaints, suggestions, and bugs to BIS.
 
Invoking the simulator.
 
Typing

	.r acrsim<cr>

Wait until a `*' is printed, then type

	(super)<cr>
 
to invoke the simulator, which comes up ready for keystroke command input.
Various compiled LISP files are loaded at this point, so you may have to
wait a teensy bit before you can proceed.

The default display mode is STEREO, SPINES only.
 
Exiting the simulator.
 
The keystroke commands `q' and `Q' will exit the simulator to LISP.
 
Exit LISP by typing
 
	(kwit)
 
which will reset the mappings of DD channels and page printers.
 
Demonstrations for beginners.
 
Invoke SIMULATOR as described on the previous pages and type
 
	zDEMO<cr>	.
 
This command loads the objects TABLE, BARM, and AXES.
It also loads a trajectory file produced by AL which shows BARM moving from
park position to a spot to pick something up, then moving to a location at
which the object is set down.
 
After return from zDEMO, the keystrokes `F' and `B' (`f' and `b') move
the simulator forwards and backwards thru the motion.
 
More Demonstrations.

There are a series of EXE files which consist of SIMULATOR commands which
can be executed to produce reasonably interesting animations.  These are
cataloged in TAKE.DOC[NEW,BIS], and a typical one can be done with:

.r acrsim
(super)
	[This may not be needed, depending on your ACRONY.INI file;
	 the simulator defaults to coming up with (SUPER) already
	 invoked, I think, but this may not be true.  If it tells you
	 `Type ? for help' then SUPER's already been invoked.]
zexe TAKE01[new,bis]<cr>
	[This shows pictures, sleeps when it wants you to talk or to let the
	 audience stare aghast.]
etc

Some notes:

The simulator is SLOW.

You hafta to fill in the words which go with each picture; if you need
explanations, let me know.

Some showmanship is required in determining what order to use in showing
things.  I have found that it's best to present the most impressive
things first to get the audience hooked and then to show the dumber demos
(like the series of models, which is slow to load and which invariably
puts people to sleep).

Commands and numeric arguments.
 
The simulator accepts two sorts of commands, the KEYSTROKE COMMANDS and
the EXTENDED (Z) COMMANDS.

All commands regard upper and lower case letters interchangeably.

KEYSTROKE COMMANDS are single keystrokes which are processed immediately
by the simulator.  Keystroke commands are typically simple actions such as
moving the camera or positioning the image on the screen or advancing
the simulation by some number of steps.

EXTENDED (Z) COMMANDS are signalled by an initial `z' and terminated by a
carriage return.  Extended commands are generally hairier than keystroke
commands.  If you erroneously type `z', then typing <alt> will cancel the
unwanted invocation of the extended command reader.
 
Some commands of each type can process numeric arguments.  Typing a digit
adds it to the $NUMBER-BUFFER.  Typing a `+' or `-' changes the
$SIGN-BUFFER.  Typing ALTMODE clears both buffers.  These buffers are
passed to commands which use them.  The execution of a command clears the
$SIGN-BUFFER and $NUMBER-BUFFER.
 
Getting ALT files from AL.

NOTE (23 October 1980).
The AL compiler has been modified so that it no longer produces ALT files
which can be simulated.  A better link between AL and SIMULATOR is expected
to appear sometime in the future.

The simulator has a limited ability to interpret trajectory files
(called `ALT files' here) produced by the AL compiler.  Such files
are intermediates in the AL compilation process, and they are normally
deleted by AL.  To KEEP such a file, use the K switch to the AL
compiler:

	.COMPIL foo.al(k)

Miscellaneous commands.

q	exits the simulator to top-level LISP

?	request help

zHELP	request help

z?	request help

zE <exp>	passes <exp> to LISP for evaluation

Objects in the world.

The simulator understands objects modelled as generalised cones by ACRONYM.

zCLEAR	removes all objects from the current world

zPARSE	reads in a new ACRONYM model file on top of the current world

Visibility of objects.

ACRONYM can display objects in three ways.  The SPINE drawing shows only
the spines of the generalised cones of the object.  The WIRE drawing shows
the object as a wire frame with no hidden surface removal.  The back
surface drawing (called here BS) removes hidden lines from individual
cones, but does not count interaction across objects:  one cone does not
obscure another cone in front of which it is.  Maybe one day we'll have a
true hidden line removal algorithm here.  Feel free to write one if you
want to.

ACRONYM objects may explicitly declare their visibility, and the simulator
won't change it.  The commands below affect only those objects which are
not explicitly visibled.  The AXES, for example, are actually one-inch
square rods, but only their spines are drawn.  The TABLE is always drawn
with back surfaces removed.  It is much faster to step forward thru an ALT
file with the arm shown as spines than with the arm shown as wires (about
12 times slower) or with back surfaces removed.

zBS	causes future displays to be back-surface removed

zSPINES	causes future displays to be spines only

zWIRES	causes future displays to be as wire-frames

Display modes:  stereo, mono.

zMONO	causes future displays to be monocular

zSTEREO	causes future displays to be cross-eyed stereo pairs

Camera parameters.

MISCELLANEOUS

O	halves the rotation angle for future keystroke changes
P	doubles the rotation angle for future keystroke changes

:	increases the focal length
;	decreases the focal length

A	resets camera to its default parameters
L	resets camera to a different default, useful for big scenes

PAN, TILT, ROLL

I	tilts the camera downwards
M	tilts the camera upwards

J	tilts the camera leftwards
K	tilts the camera rightwards

Y	rotates the image clockwise
T	rotates the image counter-clockwise

MOVING THE CAMERA
 
The camera should be imagined as being on a sphere whose center is at some
point in space.  You can change this point using the zLOOKAT command.
Generally, this point will be at or near the center of what you are
observing.  The following commands move the camera around on the sphere,
changing its azimuth and elevation thereon.

E	move the camera upwards on the sphere
X	move the camera downwards on the sphere

S	move the camera leftwards on the sphere
D	move the camera rightwards on the sphere

zIRIS	prompts for new coordinates of the camera position

zLOOKAT	prompts for new coordinates of the center of the sphere

STEREO PARAMETERS
 
,	halve the interocular distance
.	double the interocular distance
 
(	point the eyes more inwards (converge)
)	point the eyes more outwards (diverge)
 
Cameras:  naming, changing, saving, and loading.
 
At any time, the user may name the current camera parameters for future
reference by the Name Camera command
	zNC <name> <cr>
where <name> is a LISP atom.
 
A previously named camera is selected by the Change Camera command
	zCC <name> <cr>.
 
The current camera parameters can be saved in a disk file with the Save Camera
command:
	zSC <file> <cr>.
The default extension for the filename is `CAM' and the default disk area is
the user's current alias.
 
Camera parameters can be restored from a disk file with the Load Camera
command:
	zLC <file> <cr>.
The default extension for the filename is `CAM' and the default disk area is
the user's current alias.
 
P1 Mode:  the PUMA-500 closer to the door.
 
The command
	zP1<cr>
puts you into P1 mode, where the keystrokes have different meanings than
they had before.  P1 mode allows you to drive the joints of a model of P1,
the PUMA closest to the door of room 020 Margaret Jacks Hall.
 
a	increment joint 1 by 15 degrees
b	increment joint 2 by 15 degrees
c	increment joint 3 by 15 degrees
d	increment joint 4 by 15 degrees
e	increment joint 5 by 15 degrees
A	decrement joint 1 by 15 degrees
B	decrement joint 2 by 15 degrees
C	decrement joint 3 by 15 degrees
D	decrement joint 4 by 15 degrees
E	decrement joint 5 by 15 degrees
jJ	display joint angles of P1
pP	park P1 in the `READY' position (straight up);
	also resets joint speeds to 15-degrees/keystroke
qQ	exit PUMA mode (keystrokes revert)
rR	read and conform to a file of joint angles (see below)
sS	set the speed of joint motions (in degrees) to the numeric argument
x	decrement the cartesian X-position by the current speed (inches)
X	increment the cartesian X-position by the current speed (inches)
y	decrement the cartesian Y-position by the current speed (inches)
Y	increment the cartesian Y-position by the current speed (inches)
z	decrement the cartesian Z-position by the current speed (inches)
Z	increment the cartesian Z-position by the current speed (inches)
?	print a reminder of these keystroke meanings
 
The zP1 command will cause parsing of the P1 model, namely P1.MOD[SYS,BIS],
assuming that this file has not already been PARSEd.

The keystrokes `r' and `R' will prompt for a file name.  The default extension
is VJT (for Val JoinT).  The file is presumed to contain 5 numbers, namely
values for the 5 joints of the P1 arm.  The P1 model is set to this configuration.
 
P2 Mode:  the PUMA-500 further from the door.
 
The command
	zP2<cr>
puts you into P2 mode, where the keystrokes have different meanings than
they had before.  P2 mode allows you to drive the joints of a model of P2,
the PUMA farthest from the door of room 020 Margaret Jacks Hall.
 
For more information about P1 Mode, read the previous page of this document,
whereon is explained P1 mode.
 
NOTE:  the xXyYzZ commands are not yet implemented for P2.
 
ALT files.

zALT	reads an ALT file for simulation

Stepping thru an ALT file.

FORWARDS AND BACKWARDS

The following commands move the user forwards and backwards thru an ALT
file.  You can't move forwards past the end and you can't move backwards
before $TIME-OFFSET.  These commands will display intermediate pictures:
moving forward 9 steps will show you the 9 images.  The SKIP commands
will show only the end picture.

F	moves forwards by one TIME-STEP
-F	moves backwards by one TIME-STEP
#F	moves forwards by # TIME-STEPs
+#F	moves forwards by # TIME-STEPs
-#F	moves backwards by one TIME-STEP

B	moves backwards by one TIME-STEP
-B	moves forwards by one TIME-STEP
#B	moves backwards by # TIME-STEPs
+#B	moves backwards by # TIME-STEPs
-#B	moves forwards by one TIME-STEP
 
#zSF	skips the manipulator program forward by # $TIME-STEPs
zSF	skips the manipulator program forward by 1 $TIME-STEP
-#zSF	skips the manipulator program backward by # $TIME-STEPs
-zSF	skips the manipulator program backward by 1 $TIME-STEP

JUMPING AROUND

zA	skip to the beginning of the manipulator program
zZ	skip to the end of the manipulator program

#zG	skips the manipulator program to time # (in milliseconds)

CHANGING THE $TIME-STEP

z*	doubles the current $TIME-STEP
z//	halves the current $TIME-STEP

#zSTEP	sets $TIME-STEP to be # milliseconds
0zSTEP	tells the current $TIME-STEP

Driving the joints of BARM.
 
The DJ (Drive Joint) command permits the user to individually drive the
joints of the blue arm.  These commands have lousy syntax.  They will
eventually be replaced by more reasonable syntax (AL, for instance).

There are six joints, numbered 1 thru 6, but they may also be referenced by
the letters `a' thru `f' or `A' thru `F'.  The latter designations were
added because it is fairly difficult to type digits without moving one's
eyes away from the display.  Letters are easier to type by touch alone.
 
With each joint is associated its current value (designated `ji' where `i'
is 1 thru 6, etc) and its current increment (designated `∂i') which is the
amount by which ji will be changed with each Drive Joint command.

The increment can be doubled or halved by the appropriate commands (see
below).  The initial increment for rotary joints is 15 degrees.  The
initial increment for sliding joints is 1 inch.

Each joint also has an initial value, designated `Ji0'.  This is currently
0.0 for all joints.

The Drive Joint command has nine forms.

zDJ i<cr> performs Ji←Ji+∂i, incrementing the specified joint by one step.

+zDJ i<cr> peforms Ji←Ji+∂i, incrementing the specified joint by one step.

-zDJ i<cr> performs Ji←Ji-∂i, decrementing the specified joint by one step.

#zDJ i<cr> performs Ji←Ji+#*∂i, incrementing the specified joint by # steps.

+#zDJ i<cr> peforms Ji←Ji+#*∂i, incrementing the specified joint by # steps.

-#zDJ i<cr> performs Ji←Ji-#*∂i, decrementing the specified joint by # steps.

0zDJ i<cr> peforms Ji←Ji0, setting the specified joint to its initial value.

+0zDJ i<cr> performs ∂i←2*∂i, doubling the step size for the selected joint.

-0zDJ i<cr> performs ∂i←0.5*∂i, halving the step size for the selected joint.
 
All joints are returned to their initial positions by the zPARK <cr> command.
 
Collision.

SIMULATOR has a primitive form of collision detection by reporting the
intersection of certain objects.
The sets of objects which are checked for collision are:
	{ P1-HAND P1-WRIST P1-JOINT4 P1-LOWER P1-UPPER }
vs
	{ P2-HAND P2-WRIST P2-JOINT4 P2-LOWER P2-UPPER }.
 
Collision checking is controlled by the zCOLLIDE command, which prompts for
either ON or OFF.  Default is OFF.
 
You will be beeped if you move one collidable object into another.
The names of the SIMPLE-CONEs which intersect will be printed.
 
Hardcopy output.
 
You can get hardcopy of what you are seeing on the screen with the zGOD
command.

These files are labelled with:
	writer
	time
	date
	joint angles for P1
	interocular distance (stereo only)
	vergence angle (stereo only)
 
MONO
 
The command zGOD will prompt you for the name of an output file.
Three files are creating using this name and the following extensions:
	name.GOD is a GOD file of graphic commands;
	name.TXT is a file for XGPSYN which includes text and the escape
		 sequences which suck in the GOD file for listing;
	name.DO  is a command file which saves the user from explicitly
		 interacting with XGPSYN.
To get your hardcopy, issue the command
	.BATCH/NOW @name.DO
and pick up your output from the XGP when the command file is finished.

STEREO
 
The command zGOD will prompt you for the name of an output file.
Four files are creating using this name and the following extensions:
	name.LGD is a GOD file of graphic commands for the left image;
	name.RGD is a GOD file of graphic commands for the right image;
	name.TXT is a file for XGPSYN which includes text and the escape
		 sequences which suck in the GOD files for listing;
	name.DO  is a command file which saves the user from explicitly
		 interacting with XGPSYN.
To get your hardcopy, issue the command
	.BATCH/NOW @name.DO
and pick up your output from the XGP when the command file is finished.
 
Some other things to note.
 
The simulator will not display any world configuration for a time before
$TIME-OFFSET or after $END-OF-MOTIONS.
 
$TIME-OFFSET is currently 4000 ms.  Since a good AL program begins with
the statement
	MOVE BARM TO BPARK WITH DURATION = 4*SECONDS;,
we lose nothing by ignoring those first 4 seconds.
 
$END-OF-MOTIONS is set and announced after any new ALT file is read, and
corresponds to the end of the last motion in the ALT file.
 
The joint angles affected by the Drive Joint commands are entirely
different from those updated during the course of simulating an ALT file.
This is not particularly desirable, and a future version of the simulator
will use the same joint angle variables for both purposes.
 
Digest of top-level keystroke commands.
 
Digest of extended commands.
 
zTIME	reports the current value of $TIME in the simulation.
 
zTIME-HI	sets or tells the current value of $TIME-HI for simulation.
	The simulator will not move forwards past $TIME-HI.  To get the
	current value, say
		zTIME-HI<cr>	.
	To set the value, say, for example
		10000zTIME-HI<cr>	.
 
zTIME-LO	sets or tells the current value of $TIME-LO for simulation.
	The simulator will not move backwards past $TIME-LO.  To get the
	current value, say
		zTIME-LO<cr>	.
	To set the value, say, for example
		10000zTIME-LO<cr>	.
 
How to create an ACRSIM.

ACRSIM is a layer recognised by ACRONYM, and the file AUTOLD.LSP[SYS,ROD]
contains the information required to cause loading of SIMULATOR files.
If you modify SIMULATOR by adding new files or renaming old ones, be
sure to update the entries in AUTOLD.

.r acrony
		Invoke ACRONYM.
(build-system acrsim)
		This causes loading of the relevant FAS files, and then
		stores the fully loaded system as ACRSIM.DMP[1,3].

Don't mind the following error message:
;CAUTION!  NICE-ANGLE, A SYSTEM SUBR AT 301337, IS BEING REDEFINED
;    AS A SUBR BY FASL FILE ((DSK (SYS BIS)) HAND FAS)

Files used by SIMULATOR.

SCANER.LSP[SYS,BIS] parses the input
CAMERA.LSP[SYS,BIS] moves cameras around, does hard copy
COLLID.LSP[SYS,BIS] collision detection
SIMULA.LSP[SYS,BIS] for time control
BARM.LSP[SYS,BIS] moving the blue arm
VAL.LSP[SYS,BIS] handles input and output in val format
P1KB.LSP[SYS,BIS] moves the green arm
P2KB.LSP[SYS,BIS] moves the red arm
PSOLVE.LSP[SYS,BIS] puma arm solution
HAND.LSP[SYS,BIS] moves the 3-fingered hand
MODITO.LSP[SYS,BIS] moditor
HANDEL.LSP[SYS,BIS] converts high-level hand motions
STACK.LSP[SYS,BIS] for creating models which contain stacks or parallel cones

Archived announcements.

∂24-Mar-80  1803	BIS  	simulator version 13    
To:   "@SIM.DIS[DIS,BIS]"   

Now released.  Changes summarised here.  SIM.DOC[SYS,BIS] has more info.

Stereo hardcopy is now available with the zXLD command.
 
The old DEMO command has been flushed.  The simulator comes up with an ALT
file and a world of objects (BARM, TABLE, AXES.  You just type F and B
commands to move forwards and backwards if that's all you want to do.
Camera positioning is moderately hairier, so read the DOC to understand
it.
 
The HELP command used to swap from ACRONYM to E and then come back.  This
loses because ACRONYM is 510P in size, and it takes forever.  I'm afraid
the only help you'll get is from reading the DOC.
 
Report bugs and wishes to BIS.

∂13-Jul-80  1656	BIS  	simulator version 014 ...    
To:   "@SIM.DIS[DIS,BIS]"   
 
... is now released.
 
You can now drive the joints of a PUMA model under keystroke control.
 
The joint variables used in the model are probably off from those actually
used by VAL; this will be fixed soon.
 
The upper and lower arms of the model have an undesired extra taper
(take a look to see what I mean.  This can't be fixed immediately.

I won't vouch for the absolute accuracy of the geometrical details of
this model.  It's a quicky which captures the spirit of what we want.
Small errors probably exist in:  positioning of the arm on the table;
absolute dimensions of the parts; distances between joint axes.  These
will be fixed as greater accuracy is needed.

Note that the simulator is now invoked by
	.r acronym;simulator[sys,bis]
without your having to give an explicit version number.

See SIMULA.DOC[SYS,BIS] for further details.
 
Coming soon (hopefully will be an implementation of the arm solution
for the PUMA which will enable teaching in world coordinates.
 
A new version of the model editor is now loaded with the simulator.
Written by BIS and designed for convenient modelling of the PUMA arm,
this MODITOR is entirely undocumented at present.  Let me know if you
will be inconvenienced by my flushing the old MODITOR after documenting
the new one.

∂20-Jul-80  0018	BIS  	simulator version 015   
To:   "@SIM.DIS[DIS,BIS]"   

the PUMA command is flushed
it's replaced by the P1 command (since the P2 command is on the way
angles agree with VAL angles
lower arm inside upper arm in model (how come nobody noticed this?
bilinear sweeping rules are now used for upper and lower arms in the model
hardcopy now includes:  time,date,p1 joint angles
R command in P1 mode reads a file of joint angles and makes P1 conform
the P1 command reads P1 model if it wasn't already read
new default camera sees both P1 and BARM
to run moditor, use r acronym;simulator
	you'll be getting BIS' new undocumented evolving model editor
	(old moditor can be had with .r acronym;moditor.old[sys,bis]
further notes in SIMULATOR.DOC[SYS,BIS]

∂11-Aug-80  0410	BIS  	new simulator version   
To:   "@SIMULA.DIS[DIS,BIS]"

The zP2 command PARSEs a model of PUMA2 and allows keystroke control of
its joints (simulating teaching in joint coordinates.

Collision detection is approached by reporting object intersection.
SIMPLE-CONEs checked for collision are:
	{ P1-HAND P1-WRIST P1-JOINT4 P1-LOWER P1-UPPER }
vs
	{ P2-HAND P2-WRIST P2-JOINT4 P2-LOWER P2-UPPER }.
So if you use the P1 or P2 command modes to move the PUMA models, you'll get
beeped on collision of the two arms.  Note that the SIMPLE-CONEs are approximated
by right circular cylinders with hemispherical endcaps (a la Pieper; better
safe than sorry.

The S command in P1 or P2 mode sets the `speed.'  The numeric argument of
the S command determines the number of degrees a joint will move when you
give its keystroke.  Initially, this value is 15 degrees.  The P (park
keystroke resets the speed to 15 degrees/keystroke.

The zDEMO command will now cause PARSEing (if necessary of TABLE, AXES, and
BARM, and causes reading of a default ALT file for moving BARM.
 
See SIMULATOR.DOC[SYS,BIS] for further details.

∂23-Nov-80  1840	BIS  	SIMULATOR and ACRONYM   
To:   "@SIMULA.DIS[DIS,BIS]"

Remember how in the old days you had to type stuff like
	.r acronym;simulator[sys,bis]<cr>
in order to get SIMULATOR to run?

Well, that's no longer necessary.

SIMULATOR is now integrated into ACRONYM and is loaded by a simple
	.r acronym<cr>

This version includes simulated cartesian teach-box control of one PUMA.
See SIMULA.DOC[SYS,BIS] for details.

Some things remain undocumented:  HAND control and automatic grasping.

HACKERS NOTE:  The latest cross-reference (ACRONY.XXX[AID,ROD] includes
functions used by SIMULATOR.

∂18-Jun-81  0049	BIS  	make-stack & make-parallel   
To:   "@SIMULA.DIS[DIS,BIS]" at SU-AI 
Functions helpful for creating ACRONYM models with lots of parallel cones
(e.g. bed of nails or stacks of cones (e.g. turned parts are now available.
See MODITOR.DOC[SYS,BIS]/21P and the page thereafter.